Add capi.enableWebSocketResponses and provider.transport session options by dereklegenzoff · Pull Request #1711 · github/copilot-sdk

dereklegenzoff · 2026-06-17T19:25:59Z

Why

Two related WebSocket transport controls for the SDK's hand-written session options, both follow-ups to runtime PRs that were already merged/under review and explicitly called out as needing a corresponding SDK change:

capi.enableWebSocketResponses — WebSocket transport is now the default for the CAPI (Copilot API) Responses API whenever a model advertises the ws:/responses endpoint. That breaks for users behind proxies or in networks where WebSockets fail, so they need a way to opt out and fall back to the HTTP Responses transport. SDK-side follow-up to github/copilot-agent-runtime#10551 (requested in review by @SteveSandersonMS).
provider.transport — BYOK OpenAI-compatible providers need the opposite knob: an opt-in to deliver Responses API requests over a persistent WebSocket connection instead of HTTP (better for long-running, tool-call-heavy sessions that benefit from incremental previous_response_id continuations). SDK-side follow-up to github/copilot-agent-runtime#9557.

These are two distinct, complementary toggles: capi.enableWebSocketResponses: false opts out of WS for GitHub's Copilot API; provider.transport: "websockets" opts in to WS for your own BYOK endpoint. They are independent and coexist.

What

1. `capi.enableWebSocketResponses`

New nested session option capi: { enableWebSocketResponses?: boolean } on session create and resume. WebSocket transport is enabled by default when the model advertises ws:/responses; set this to false to force the HTTP Responses transport instead. Setting it to false is equivalent to setting the COPILOT_CLI_DISABLE_WEBSOCKET_RESPONSES environment variable (the env var name is unchanged). Scoped under a capi namespace (not a top-level option) by design: a single session can host multiple providers (CAPI + BYOK), so transport choice is conceptually provider-level.

Wire shape: session.create / session.resume params gain capi: { enableWebSocketResponses: false }, omitted entirely when unset.

2. `provider.transport`

New field transport?: "http" | "websockets" (default "http") on the BYOK ProviderConfig. When "websockets", Responses API requests for that OpenAI-compatible provider are delivered over a persistent WebSocket connection. Flows through the already-wired provider option on session create and resume.

Wire shape: provider.transport serializes as a plain camelCase string, omitted when unset.

Approach

Both options are hand-written pass-throughs. Session create/resume options — and the ProviderConfig type — are hand-written in every language (not codegen-driven), so these ship independently of the runtime releases:

capi is a new nested type mirroring the existing provider (BYOK) nested option exactly, wired into both the create and resume RPC params in every language.
transport is a single new field on ProviderConfig mirroring the existing wireApi field; it needs no new wiring because the whole provider object is already serialized end-to-end.

Per-language summary:

Node.js (reference): CapiSessionOptions interface + SessionConfigBase.capi wired in create/resume + re-export; transport on ProviderConfig. Tests added.
Python: CapiSessionOptions TypedDict + camelCase wire helper + capi kwarg + export; transport on ProviderConfig TypedDict + wire mapping. Tests added.
Go: CapiSessionOptions struct + Capi on configs/wire requests/builders; Transport on ProviderConfig. Tests added.
Java: new CapiSessionOptions (fluent + Jackson) wired in SessionRequestBuilder for create/resume; transport field + getter/fluent-setter on ProviderConfig. Tests added.
.NET: CapiSessionOptions class + Capi on SessionConfigBase (copy-ctor, both request records, serializer context); Transport on ProviderConfig. Tests added.
Rust: CapiSessionOptions (#[non_exhaustive] + builders) + capi on configs/wire; transport field + with_transport builder on ProviderConfig. Tests added.

Compatibility

Both fields are harmless no-ops on a CLI runtime that predates the corresponding runtime PR, so the SDK changes are safe to land ahead of (or independently of) the runtime releases.

Deferred follow-up (by design)

No @github/copilot dependency bump / codegen re-run. The current schema does not contain a generated CapiSessionOptions, and the generated ProviderConfig is not the consumer-facing type (the SDK exports a hand-written one). Once the runtime PRs publish, an optional bump + codegen re-run can produce generated types; the hand-written pass-throughs are sufficient in the meantime.
No session.options.update (live update) wiring. This PR covers session create and resume only.

Testing

Built and ran the per-language unit suites for every change — Node.js, Python, Go, Java, Rust, and .NET all pass locally (formatting/lint/clippy/spotless clean where applicable). e2e suites that require the replay-proxy harness were out of scope for local verification.

Refs github/copilot-agent-runtime#10551, github/copilot-agent-runtime#9557

Add the capi.disableWebSocketResponses opt-out to session create/resume across all six SDK languages, so consumers in proxy/WebSocket-blocked environments can fall back to the HTTP Responses transport for the CAPI Responses API. SDK-side follow-up to github/copilot-agent-runtime#10551, which makes WebSocket transport the default for CAPI and adds this opt-out. The field is a hand-written pass-through mirroring the existing provider (BYOK) nested option, wired into session.create and session.resume. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

This PR adds a provider-scoped session option capi.disableWebSocketResponses to the session create and resume request shapes across all SDK languages, allowing users to opt out of the default WebSocket-based CAPI Responses transport and fall back to HTTP (useful in proxy-restricted environments).

Changes:

Introduces CapiSessionOptions (language-idiomatic) and threads it through session create/resume configs and wire payloads.
Ensures the option is omitted from the wire payload when unset (via optional fields / non-null serialization).
Adds/extends unit tests to verify forwarding + serialization behavior.

Show a summary per file

File	Description
rust/src/wire.rs	Adds optional `capi` field to Rust create/resume wire payload structs.
rust/src/types.rs	Introduces `CapiSessionOptions`, adds `capi` to SessionConfig/ResumeSessionConfig, and adds serialization tests.
python/test_client.py	Adds unit test ensuring `capi` options are forwarded on create/resume.
python/copilot/client.py	Adds `CapiSessionOptions` TypedDict, wire conversion helper, and `capi` kwarg wiring for create/resume.
python/copilot/init.py	Re-exports `CapiSessionOptions` from the package surface.
nodejs/test/client.test.ts	Adds test verifying `capi` forwarding on `session.create` and `session.resume`.
nodejs/src/types.ts	Adds `CapiSessionOptions` and `capi?:` to shared session config base types.
nodejs/src/index.ts	Re-exports `CapiSessionOptions` in public entrypoint.
nodejs/src/client.ts	Forwards `config.capi` into `session.create` / `session.resume` request params.
java/src/test/java/com/github/copilot/JsonIncludeNonNullTest.java	Adds JSON non-null include annotation coverage for `CapiSessionOptions`.
java/src/test/java/com/github/copilot/CapiSessionOptionsTest.java	New test suite covering Java option defaults, fluent setters, and request inclusion/omission.
java/src/main/java/com/github/copilot/SessionRequestBuilder.java	Wires `config.getCapi()` into create/resume request builders.
java/src/main/java/com/github/copilot/rpc/SessionConfig.java	Adds `capi` field + getter/setter + clone propagation.
java/src/main/java/com/github/copilot/rpc/ResumeSessionConfig.java	Adds `capi` field + getter/setter + clone propagation.
java/src/main/java/com/github/copilot/rpc/CreateSessionRequest.java	Adds `capi` JSON property + accessor methods on the wire request type.
java/src/main/java/com/github/copilot/rpc/ResumeSessionRequest.java	Adds `capi` JSON property + accessor methods on the wire request type.
java/src/main/java/com/github/copilot/rpc/CapiSessionOptions.java	New Java RPC type with Jackson annotations and fluent setter for `disableWebSocketResponses`.
go/types.go	Adds `CapiSessionOptions`, threads it through session configs and create/resume request structs.
go/client.go	Forwards `config.Capi` into create/resume RPC request builders.
go/client_test.go	Adds tests ensuring `capi.disableWebSocketResponses` is serialized/forwarded and omitted when unset.
dotnet/test/Unit/SerializationTests.cs	Adds serialization coverage for `CapiSessionOptions` and create/resume request inclusion/omission.
dotnet/test/Unit/CloneTests.cs	Extends clone coverage to ensure `Capi` is copied consistently.
dotnet/src/Types.cs	Introduces `CapiSessionOptions`, adds it to SessionConfigBase, and registers it for source-gen serialization.
dotnet/src/Client.cs	Threads `config.Capi` through internal create/resume request records and serializer context.

Copilot's findings

Files reviewed: 24/24 changed files
Comments generated: 0

Add the BYOK provider `transport` field ("http" | "websockets", default "http") to the hand-written ProviderConfig across all six SDK languages, so BYOK OpenAI-compatible providers can opt into delivering Responses API requests over a persistent WebSocket connection instead of HTTP. SDK-side follow-up to github/copilot-agent-runtime#9557, which adds the runtime `transport` option. The SDK's consumer-facing ProviderConfig is hand-written (not generated from the schema), so the field is added as a pass-through mirroring the existing `wireApi` field, flowing through the already-wired `provider` option on session create and resume. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…isable-websocket-responses Resolve conflicts by keeping both the new capi.disableWebSocketResponses / provider.transport options from this branch and the experimental multi-provider BYOK (providers/models) additions from main across all six SDK languages. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Update the CapiSessionOptions type-level doc summary in each language to lead with the spelled-out 'Copilot API (CAPI)' form on first use, matching the existing docs convention (and the Node SDK, which already did this). Python's class docstring previously never expanded the acronym. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Rename the hand-written capi session option from disableWebSocketResponses (default false) to enableWebSocketResponses (default true) across all six language SDKs, matching the inverted shape in runtime PR github/copilot-agent-runtime#10551. Setting it to false forces the HTTP Responses transport, equivalent to the unchanged COPILOT_CLI_DISABLE_WEBSOCKET_RESPONSES environment variable. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-06-22T19:41:32Z

Cross-SDK Consistency Review ✅

Both new features (capi.enableWebSocketResponses and provider.transport) are implemented consistently across all six SDK implementations. No cross-language consistency issues found.

Feature 1: `CapiSessionOptions` with `enableWebSocketResponses`

SDK	Type	Field	On create	On resume	Wire key
Node.js	`CapiSessionOptions` interface	`enableWebSocketResponses?: boolean`	✅ `capi?` on `SessionConfigBase`	✅ (inherited)	`enableWebSocketResponses`
Python	`CapiSessionOptions` TypedDict	`enable_web_socket_responses: bool`	✅ `capi` kwarg	✅ `capi` kwarg	`enableWebSocketResponses`
Go	`CapiSessionOptions` struct	`EnableWebSocketResponses *bool`	✅ `Capi *CapiSessionOptions`	✅ `Capi` field	`enableWebSocketResponses`
.NET	`CapiSessionOptions` class	`EnableWebSocketResponses bool?`	✅ `Capi` on `SessionConfigBase`	✅ (inherited)	`enableWebSocketResponses`
Java	`CapiSessionOptions` class	`getEnableWebSocketResponses()` / `setEnableWebSocketResponses()`	✅ `setCapi()` on `SessionConfig`	✅ `setCapi()` on `ResumeSessionConfig`	`enableWebSocketResponses`
Rust	`CapiSessionOptions` struct	`enable_web_socket_responses: Option<bool>`	✅ `with_capi()` on `SessionConfig`	✅ `with_capi()` on `ResumeSessionConfig`	`enableWebSocketResponses`

Feature 2: `provider.transport`

SDK	Field	Type
Node.js	`transport?`	`"http" \| "websockets"`
Python	`transport`	`Literal["http", "websockets"]` (optional in TypedDict)
Go	`Transport`	`string` (`omitempty`)
.NET	`Transport`	`string?`
Java	`transport`	`String` (getter/setter)
Rust	`transport`	`Option<String>` + `with_transport()` builder

All SDKs serialize correctly to the same camelCase wire format (capi.enableWebSocketResponses, transport), use appropriate language idioms for optional/nullable types, include the CapiSessionOptions type in public exports where applicable (Node.js index.ts, Python __init__.py), and include unit tests covering both features.

Generated by SDK Consistency Review Agent for issue #1711 · sonnet46 1.3M · ◷

…ons (#1711) * Add capi.disableWebSocketResponses session option Add the capi.disableWebSocketResponses opt-out to session create/resume across all six SDK languages, so consumers in proxy/WebSocket-blocked environments can fall back to the HTTP Responses transport for the CAPI Responses API. SDK-side follow-up to github/copilot-agent-runtime#10551, which makes WebSocket transport the default for CAPI and adds this opt-out. The field is a hand-written pass-through mirroring the existing provider (BYOK) nested option, wired into session.create and session.resume. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add provider.transport BYOK option Add the BYOK provider `transport` field ("http" | "websockets", default "http") to the hand-written ProviderConfig across all six SDK languages, so BYOK OpenAI-compatible providers can opt into delivering Responses API requests over a persistent WebSocket connection instead of HTTP. SDK-side follow-up to github/copilot-agent-runtime#9557, which adds the runtime `transport` option. The SDK's consumer-facing ProviderConfig is hand-written (not generated from the schema), so the field is added as a pass-through mirroring the existing `wireApi` field, flowing through the already-wired `provider` option on session create and resume. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Lead with spelled-out 'Copilot API (CAPI)' on first mention Update the CapiSessionOptions type-level doc summary in each language to lead with the spelled-out 'Copilot API (CAPI)' form on first use, matching the existing docs convention (and the Node SDK, which already did this). Python's class docstring previously never expanded the acronym. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Invert capi flag to enableWebSocketResponses (default true) Rename the hand-written capi session option from disableWebSocketResponses (default false) to enableWebSocketResponses (default true) across all six language SDKs, matching the inverted shape in runtime PR github/copilot-agent-runtime#10551. Setting it to false forces the HTTP Responses transport, equivalent to the unchanged COPILOT_CLI_DISABLE_WEBSOCKET_RESPONSES environment variable. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings June 17, 2026 19:26

dereklegenzoff requested a review from a team as a code owner June 17, 2026 19:26

Copilot started reviewing on behalf of dereklegenzoff June 17, 2026 19:26 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

dereklegenzoff changed the title ~~Add capi.disableWebSocketResponses session option~~ Add capi.disableWebSocketResponses and provider.transport session options Jun 18, 2026

This comment has been minimized.

Sign in to view

stephentoub reviewed Jun 22, 2026

View reviewed changes

Comment thread dotnet/src/Types.cs

stephentoub reviewed Jun 22, 2026

View reviewed changes

Comment thread dotnet/src/Types.cs

stephentoub reviewed Jun 22, 2026

View reviewed changes

Comment thread dotnet/src/Types.cs Outdated

stephentoub approved these changes Jun 22, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

dereklegenzoff changed the title ~~Add capi.disableWebSocketResponses and provider.transport session options~~ Add capi.enableWebSocketResponses and provider.transport session options Jun 22, 2026

stephentoub added this pull request to the merge queue Jun 22, 2026

Merged via the queue into main with commit a3dbdd1 Jun 22, 2026
40 checks passed

stephentoub deleted the dereklegenzoff/capi-disable-websocket-responses branch June 22, 2026 20:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add capi.enableWebSocketResponses and provider.transport session options#1711

Add capi.enableWebSocketResponses and provider.transport session options#1711
stephentoub merged 5 commits into
mainfrom
dereklegenzoff/capi-disable-websocket-responses

dereklegenzoff commented Jun 17, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

github-actions Bot commented Jun 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

dereklegenzoff commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What

1. capi.enableWebSocketResponses

2. provider.transport

Approach

Compatibility

Deferred follow-up (by design)

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

github-actions Bot commented Jun 22, 2026

Cross-SDK Consistency Review ✅

Feature 1: CapiSessionOptions with enableWebSocketResponses

Feature 2: provider.transport

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dereklegenzoff commented Jun 17, 2026 •

edited

Loading

1. `capi.enableWebSocketResponses`

2. `provider.transport`

Feature 1: `CapiSessionOptions` with `enableWebSocketResponses`

Feature 2: `provider.transport`